DropdownMenu

Kind of class:class
Inherits from:Button < UIComponent < MovieClip
Classpath:gfx.controls.DropdownMenu
File last modified:Tuesday, 29 June 2010, 09:03:27
The DropdownMenu wraps the behavior of a button and a list. Clicking on this component opens a list that contains the elements to be selected. The DropdownMenu displays only the selected element in its idle state. It can be configured to use either the ScrollingList or the TileList, to which either a ScrollBar or ScrollIndicator can be paired with. The list is populated via an installed DataProvider. The DropdownMenu’s list element is populated via a DataProvider. The dataProvider is assigned via code, as shown in the example below:
dropdownMenu.dataProvider = ["item1", "item2", "item3", "item4"];

Inspectable Properties
The inspectable properties of the DropdownMenu component are:
  • visible: Hides the component if set to false.
  • disabled: Disables the component if set to true.
  • dropdown: Symbol name of the list component (ScrollingList or TileList) to use with the DropdownMenu component.
  • itemRenderer: Symbol name of the list component's itemRenderer.
  • dropdownWidth: Width of the dropdown list. If this value is -1, then the DropdownMenu will size the list to the component’s width.
  • itemRenderer: Symbol name of the dropdown list’s item renderer. Created by the dropdown list instance.
  • scrollBar: Symbol name of the dropdown list’s scroll bar. Created by the dropdown list instance. If value is empty, then the dropdown list will have no scroll bar.
  • margin: The margin between the boundary of the list component and the list items created internally. This margin also affects the automatically generated scrollbar.
  • paddingTop:Extra padding at the top for the list items. Does not affect the automatically generated scrollbar.
  • paddingBottom:Extra padding at the bottom for the list items. Does not affect the automatically generated scrollbar.
  • paddingLeft:Extra padding on the left side for the list items. Does not affect the automatically generated scrollbar.
  • paddingRight:Extra padding on the right side for the list items. Does not affect the automatically generated scrollbar.
  • thumbOffsetTop:Scrollbar thumb top offset. This property has no effect if the list does not automatically create a scrollbar instance.
  • thumbOffsetBottom:Scrollbar thumb bottom offset. This property has no effect if the list does not automatically create a scrollbar instance.
  • thumbSizeFactor:Page size factor for the scrollbar thumb. A value greater than 1.0 will increase the thumb size by the given factor. This value has no effect if a scrollbar is not attached to the list.
  • offsetX:Horizontal offset of the dropdown list from the dropdown button position. A positive value moves the list to the right of the dropdown button horizontal position.
  • offsetY:Vertical offset of the dropdown list from the dropdown button. A positive value moves the list away from the button.
  • extent:An extra width offset that can be used in conjunction with offsetX. This value has no effect if the dropdownWidth property is set to a value other than -1.
  • direction:The list open direction. Valid values are "up" and "down".
  • enableInitCallback: If set to true, _global.CLIK_loadCallback() will be fired when a component is loaded and _global.CLIK_unloadCallback will be called when the component is unloaded. These methods receive the instance name, target path, and a reference the component as parameters. _global.CLIK_loadCallback and _global.CLIK_unloadCallback should be overriden from the game engine using GFx FunctionObjects.
  • soundMap: Mapping between events and sound process. When an event is fired, the associated sound process will be fired via _global.gfxProcessSound, which should be overriden from the game engine using GFx FunctionObjects.
States
The DropdownMenu is toggled when opened, and therefore needs the same states as a ToggleButton or CheckBox that denote the selected state. These states include
  • an up or default state.
  • an over state when the mouse cursor is over the component, or when it is focused.
  • a down state when the button is pressed.
  • a disabled state.
  • a selected_up or default state.
  • a selected_over state when the mouse cursor is over the component, or when it is focused.
  • a selected_down state when the button is pressed.
  • a selected_disabled state.
These are the minimal set of keyframes that should be in a DropdownMenu. The extended set of states and keyframes supported by the Button component, and consequently the DropdownMenu component, are described in the Getting Started with CLIK Buttons document.

Events
All event callbacks receive a single Object parameter that contains relevant information about the event. The following properties are common to all events.
  • type: The event type.
  • target: The target that generated the event.
The events generated by the DropdownMenu component are listed below. They are the same as the Button component with the exception of the change event. The properties listed next to the event are provided in addition to the common properties.
  • show: The component's visible property has been set to true at runtime.
  • hide: The component's visible property has been set to false at runtime.
  • focusIn: The component has received focus.
  • focusOut: The component has lost focus.
  • select: The component's selected property has changed.
    • selected: The selected property of the Button. Boolean type.
  • stateChange: The button's state has changed.
    • state: The Button's new state. String type. Values "up", "over", "down", etc.
  • rollOver: The mouse cursor has rolled over the button.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • rollOut: The mouse cursor has rolled out of the button.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • press: The button has been pressed.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • doubleClick: The button has been double clicked. Only fired when the Button.doubleClickEnabled property is set.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • click: The button has been clicked.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • dragOver: The mouse cursor has been dragged over the button (while the left mouse button is pressed).
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • dragOut: The mouse cursor has been dragged out of the button (while the left mouse button is pressed).
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • releaseOutside: The mouse cursor has been dragged out of the button and the left mouse button has been released.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.

Summary


Constructor
Instance properties
  • isOpen
    • The current visible state of the dropdown component.
  • selectedItem
    • A reference to the currently selected item in the dataProvider.
  • direction
    • Direction the list opens.
  • soundMap
  • dropdown
    • Sets the class or instance to use as a dropdown.
  • itemRenderer
    • Sets the linkage ID to use as the dropdown's item renderer, which will be created by the dropdown list component.
  • scrollBar
    • Sets the class or instance to use as the dropdown's scrollbar.
  • dropdownWidth
    • The width of the dropdown.
  • rowCount
    • The number of rows to display in the dropdown.
  • dataProvider
    • The data model displayed in the component.
  • selectedIndex
    • The index of the item that is selected in a single-selection list.
  • labelField
    • The name of the field in the dataProvider to be displayed as the label for the TextInput field.
  • labelFunction
    • The function used to determine the label for an item.
Instance properties inherited from Button
_autoSize _disableConstraints _disableFocus _group _label _selected autoRepeat autoSize buttonRepeatDelay buttonRepeatDuration buttonRepeatInterval constraints data disableConstraints disabled disableFocus doubleClickDuration doubleClickEnabled doubleClickInterval focusIndicator group groupName inspectableGroupName label labelID lockDragStateChange pressedByKeyboard selected soundMap state stateMap textField toggle
Instance properties inherited from UIComponent
__height __width _disabled _displayFocus _focused addEventListener cleanUpEvents disabled dispatchEvent displayFocus enableInitCallback focused focusHandlerReference focusTarget hasEventListener height initialized invalidationIntervalID removeAllEventListeners removeEventListener sizeIsInvalid soundMap visible width
Class methods
Class methods inherited from UIComponent
createInstance
Instance methods
  • itemToLabel
    • Convert an item to a label string using the labelField and labelFunction.
  • open
    • Open the dropdown list.
  • close
    • Close the dropdown list.
  • invalidateData
    • The current data has become invalid, usually via a data change.
  • setSize
    • Sets the width and height of the component at the same time using internal sizing mechanisms.
  • handleInput
    • Handle input from the game, via controllers or keyboard.
Instance methods inherited from Button
alignForAutoSize beginButtonRepeat calculateWidth changeFocus clearRepeatInterval configUI doubleClickExpired draw getStatePrefixes handleButtonRepeat handleClick handleDragOut handleDragOver handleInput handleMousePress handleMouseRelease handleMouseRollOut handleMouseRollOver handlePress handleRelease handleReleaseOutside setSize setState toString updateAfterStateChange
Instance methods inherited from UIComponent
changeFocus configUI dispatchEventAndSound dispatchEventToGame draw handleInput initSize invalidate onLoad onLoadImpl onMouseWheel onUnload scrollWheel setSize toString validateNow

Constructor

Instance properties

dataProvider

dataProvider:Object
(read,write)

The data model displayed in the component. The dataProvider can be an Array or any object exposing the appropriate API, defined in the IDataProvider interface. If an Array is set as the dataProvider, functionality will be mixed into it by the DataProvider.initialize method. When a new DataProvider is set, the selectedIndex property will be reset to 0.
See also:

direction

direction:String = "down"
(read,write)

Direction the list opens. Valid values are "up" and "down".
Component metadata:
    Inspectable
    defaultValue:
    "down"
    enumeration:
    "up,down"
    verbose:
    1

    isOpen

    isOpen:Boolean = false
    (read,write)

    The current visible state of the dropdown component. When the dropdown is open, it will receive input from the user.

    itemRenderer

    itemRenderer:Object
    (read,write)

    Sets the linkage ID to use as the dropdown's item renderer, which will be created by the dropdown list component.

    labelField

    labelField:String
    (read,write)

    The name of the field in the dataProvider to be displayed as the label for the TextInput field. A labelFunction will be used over a labelField if it is defined.
    See also:

    labelFunction

    labelFunction:Function
    (read,write)

    The function used to determine the label for an item. A labelFunction will override a labelField if it is defined.
    See also:

    rowCount

    rowCount:Number
    (read,write)

    The number of rows to display in the dropdown. The autoRowCount property on the dropdown determines how that property is applied. If the length of the dataProvider is less than the rowCount, only the number of items in the dataProvider will be displayed.

    scrollBar

    scrollBar:Object
    (read,write)

    Sets the class or instance to use as the dropdown's scrollbar. If a linkage ID is specified, it will be created by the dropdown list component. The scrollbar property will return the persistent MovieClip instance created or referenced by the DropdownMenu's list so properties can be set on it directly.

    selectedIndex

    selectedIndex:Number
    (read,write)

    The index of the item that is selected in a single-selection list. The DropdownMenu will always have a selectedIndex of 0 or greater, unless there is no data.

    selectedItem

    selectedItem:Object
    (read,write)

    A reference to the currently selected item in the dataProvider.

    soundMap

    soundMap:Object = { theme:"default", focusIn:"focusIn", focusOut:"focusOut", select:"select", rollOver:"rollOver", rollOut:"rollOut", press:"press", doubleClick:"doubleClick", click:"click" }
    (read,write)

    Component metadata:
      Inspectable
      defaultValue:
      "theme
      type:
      "Object"

      Instance methods

      close

      function close (
      ) : Void

      Close the dropdown list. The list is not destroyed, the visible property is set to false. The selected property of the DropdownMenu is set to false when closed.

      handleInput

      function handleInput (
      details:InputDetails, pathToFocus:Array) : Boolean

      Handle input from the game, via controllers or keyboard. The default handleInput will handle standalone and composite components.
      Parameters:
      details :
      An InputDetails object containing details from the interaction.
      pathToFocus:
      A list of children in the focus path that are below this component. Components are responsible for calling handleInput() on the next component in the pathToFocus unless they choose to intercept the call.
      Overrides:

      invalidateData

      function invalidateData (
      ) : Void

      The current data has become invalid, usually via a data change. The component requests a data update from the dataProvider.

      itemToLabel

      function itemToLabel (
      item:Object) : String

      Convert an item to a label string using the labelField and labelFunction.
      Parameters:
      item:
      The item to convert to a label.
      Returns:
      • The converted label string.
      See also:

      open

      function open (
      ) : Void

      Open the dropdown list. The selected and isOpen properties of the DropdownMenu are set to true when open. Input will be passed to the dropdown when it is open before it is handled by the DropdownMenu.

      setSize

      function setSize (
      width:Number, height:Number) : Void

      Sets the width and height of the component at the same time using internal sizing mechanisms.
      Parameters:
      width :
      The new width of the component.
      height:
      The new height of the component.
      Overrides: